wiki / entities / Codex CLI
Type: entity
Confidence: 0.90
Created: 2026-04-15
Updated: 2026-04-19
Tags: 技术工具工具与框架

Codex CLI

OpenAI 以 Rust 重写并开源的本地编码 Agent。不是聊天机器人，而是一套把 LLM 决策与 OS 级执行边界融合的系统工程——运行在本地终端，读仓库、改文件、跑命令。

一句话定义

LLM 推理引擎 + OS 级沙箱执行器 + 人机协同审批协议 + MCP 协议总线

整体分层架构

层 组件 职责
用户接入层 TUI / codex exec / App Server 用户交互入口
会话管理层 Session Store / Transcript / Resume / Subagent Pool 会话持久化
Agent Core codex-rs/core 业务逻辑、Model I/O、Tool Dispatch
策略层 ExecPolicy ExecPolicy</td> </tr> <tr> <td>协议层</td> <td>[[MCP协议层 双向 MCP：客户端连工具，服务端暴露自身
Claude Code 沙箱机制</td> <td>沙箱层 Codex沙箱系统

核心组件（C1–C9）

编号 组件 主要文件/crate
C1 TUI codex-rs/tui/
C2 Exec Engine core/exec.rs, core/spawn.rs
C3 Codex沙箱系统 linux-sandbox/, macOS seatbelt
C4 ExecPolicy codex-rs/execpolicy/
C5 Codex会话管理器 core/session*.rs
C6 MCP协议层 protocol, mcp-server
C7 Codex多Agent调度 core/subagent*.rs
C8 Codex配置系统 config.toml
C9 Model Layer core/model*.rs

组件依赖关系

config.toml ──────────────────────────────────────┐
                                                   ▼
AGENTS.md ──► core (业务逻辑) ──► ExecPolicy ──► Sandbox
                │                      │
                ├──► Session Manager   └──► Approval Gate ──► TUI
                │
                ├──► MCP Client ──► 外部工具服务器
                │
                └──► Subagent Pool ──► 并行 core 实例

关键架构决策

Rust 重写

原版为 TypeScript，2025 年迁移 Rust 的核心理由： - 原生沙箱绑定：Landlock/seccomp 必须在系统调用层做，应用层做不到 - 零依赖静态二进制，消除 Node.js runtime 依赖 - 确定性内存，无 GC 抖动 - 真并发（Tokio async/await）

工程智慧：选 Rust 不只是"性能更好"，更是为了在内核层做安全隔离。

Write Tools 策略

支持 write / patch 两种写入粒度，相比 Claude Code 的三件套（write / str_replace / patch）少一种粒度。使用 OS 级隔离机制，包括 macOS 上的 sandbox-exec（Seatbelt）和 Linux 上的 landlock + seccomp 过滤系统调用，提供内核级别的隔离强度。

提供三种模式（suggest / auto-edit / full-auto），分别对应不同的文件系统权限和网络权限。采用 suggest 模式（先生成所有 diff 再统一审批），让用户可以看到整个计划再决定是否执行，比逐步确认更有全局感。

大文件处理采用行范围读取策略，与 Claude Code 的 Symbol-level 读取方式不同。

Policy-First 设计

先声明策略，再执行——而非"先执行再道歉"：

[用户配置] approval_policy + sandbox_mode
         ↓
[ExecPolicy] 每条命令过策略引擎
         ↓
[Sandbox]  OS 内核强制执行

策略层（意图）与沙箱层（执行边界）独立但协同，沙箱兜底。

Wire Protocol 解耦

核心业务逻辑通过 Wire Protocol（codex-rs/protocol）与 UI 层解耦： - TUI、App Server、IDE Extension 共用同一个 core crate - 支持 Python/TypeScript 客户端通过协议接入 - Codex 自身可作为 MCP Server 被其他 Agent 调用

三道防线（不确定性 → 确定性）

LLM 输出是随机的，系统执行必须是可控的，用三道防线解决：

  1. ExecPolicy（意图过滤） — allow / prompt / forbidden 三态决策
  2. Approval Gate（人机协同） — 不确定命令暂停等待人类批准
  3. OS Sandbox（执行隔离） — 内核级强制，LLM 无法绕过

来源

← Cocos2d-x Coinbase →